3D Graphics Programming with QuickDraw 3D 1.5.4

Managing View Hints Objects

QuickDraw 3D provides routines that you can use to create and manage view hints objects. A view hints object is an object in a metafile that gives hints about how to render a scene. You can use that information to configure a view object, or you can choose to ignore it.

A view hints object contains specific information, derived from a view object and stored in a 3DMF file, that is separate from the group model submitted with a view. The view hints object is created from an existing view object using the Q3ViewHints_New call and should be written out at the beginning of the 3DMF file, followed by the group model for a scene. When an application reads a 3DMF file it should check for view hints and set up the view with the view hints settings if it wishes to preserve a scene's appearance between applications.

View hints may include instructions about the renderer, camera, lights, and view attributes, plus other information in the draw context such as the window's dimensions, mask state, mask bitmap, and clear image color. The version 1.5.1 QuickDraw 3D Viewer source code uses the following view hints information and applies it to the model's view if a view hints object is found while reading a 3DMF file:

light group
camera
renderer
window dimensions
clear image color.

Q3ViewHints_New

You can use the Q3ViewHints_New function to create a new view hints object.



 
TQ3ViewHintsObject Q3ViewHints_New (TQ3ViewObject view);

view: A view.

DESCRIPTION

The Q3ViewHints_New function returns, as its function result, a new view hints object that incorporates the view configuration information of the view object specified by the view parameter.

Q3ViewHints_GetRenderer

You can use the Q3ViewHints_GetRenderer function to get the renderer associated with a view hints object.



 
TQ3Status Q3ViewHints_GetRenderer (

                     TQ3ViewHintsObject viewHints, 

                     TQ3RendererObject *renderer);

viewHints: A view hints object.
renderer: On exit, the renderer currently associated with the specified view hints object.

DESCRIPTION

The Q3ViewHints_GetRenderer function returns, in the renderer parameter, the renderer currently associated with the view hints object specified by the viewHints parameter. The reference count of that renderer is incremented.

Q3ViewHints_SetRenderer

You can use the Q3ViewHints_SetRenderer function to set the renderer associated with a view hints object.



 
TQ3Status Q3ViewHints_SetRenderer (

                     TQ3ViewHintsObject viewHints, 

                     TQ3RendererObject renderer);

viewHints: A view hints object.
renderer: A renderer object.

DESCRIPTION

The Q3ViewHints_SetRenderer function attaches the renderer specified by the renderer parameter to the view hints object specified by the viewHints parameter. The reference count of the specified renderer is incremented. In addition, if some other renderer was already attached to the specified view hints object, the reference count of that renderer is decremented.

Q3ViewHints_GetCamera

You can use the Q3ViewHints_GetCamera function to get the camera associated with a view hints object.



 
TQ3Status Q3ViewHints_GetCamera (

                     TQ3ViewHintsObject viewHints, 

                     TQ3CameraObject *camera);

viewHints: A view hints object.
camera: On exit, the camera object currently associated with the specified view hints object.

DESCRIPTION

The Q3ViewHints_GetCamera function returns, in the camera parameter, the camera currently associated with the view hints object specified by the viewHints parameter. The reference count of that camera is incremented.

Q3ViewHints_SetCamera

You can use the Q3ViewHints_SetCamera function to set the camera associated with a view hints object.



 
TQ3Status Q3ViewHints_SetCamera (

                     TQ3ViewHintsObject viewHints, 

                     TQ3CameraObject camera);

viewHints: A view hints object.
camera: A camera object.

DESCRIPTION

The Q3ViewHints_SetCamera function attaches the camera specified by the camera parameter to the view hints object specified by the viewHints parameter. The reference count of the specified camera is incremented. In addition, if some other camera was already attached to the specified view hints object, the reference count of that camera is decremented.

Q3ViewHints_GetLightGroup

You can use the Q3ViewHints_GetLightGroup function to get the light group associated with a view hints object.



 
TQ3Status Q3ViewHints_GetLightGroup (

                     TQ3ViewHintsObject viewHints, 

                     TQ3GroupObject *lightGroup);

viewHints: A view hints object.
lightGroup: On exit, the light group currently associated with the specified view hints object.

DESCRIPTION

The Q3ViewHints_GetLightGroup function returns, in the lightGroup parameter, the light group currently associated with the view hints object specified by the viewHints parameter. The reference count of that light group is incremented.

Q3ViewHints_SetLightGroup

You can use the Q3ViewHints_SetLightGroup function to set the light group associated with a view hints object.



 
TQ3Status Q3ViewHints_SetLightGroup (

                     TQ3ViewHintsObject viewHints, 

                     TQ3GroupObject lightGroup);

viewHints: A view hints object.
lightGroup: A light group.

DESCRIPTION

The Q3ViewHints_SetLightGroup function attaches the light group specified by the lightGroup parameter to the view hints object specified by the viewHints parameter. The reference count of the specified light group is incremented. In addition, if some other light group was already attached to the specified view hints object, the reference count of that light group is decremented.

Q3ViewHints_GetAttributeSet

You can use the Q3ViewHints_GetAttributeSet function to get the current attribute set associated with a view hints object.



 
TQ3Status Q3ViewHints_GetAttributeSet (

                     TQ3ViewHintsObject viewHints, 

                     TQ3AttributeSet *attributeSet);

viewHints: A view hints object.
attributeSet: On exit, the attribute set currently associated with the specified view hints object.

DESCRIPTION

The Q3ViewHints_GetAttributeSet function returns, in the attributeSet parameter, the current attribute set of the view hints object specified by the viewHints parameter. The reference count of the attribute set is incremented.

Q3ViewHints_SetAttributeSet

You can use the Q3ViewHints_SetAttributeSet function to set the attribute set associated with a view hints object.



 
TQ3Status Q3ViewHints_SetAttributeSet (

                     TQ3ViewHintsObject viewHints, 

                     TQ3AttributeSet attributeSet);

viewHints: A view hints object.
attributeSet: An attribute set.

DESCRIPTION

The Q3ViewHints_SetAttributeSet function attaches the attribute set specified by the attributeSet parameter to the view hints object specified by the viewHints parameter. The reference count of the specified attribute set is incremented. In addition, if some other attribute set was already attached to the specified view hints object, the reference count of that attribute set is decremented.

Q3ViewHints_GetDimensionsState

You can use the Q3ViewHints_GetDimensionsState function to get the dimension state associated with a view hints object.



 
TQ3Status Q3ViewHints_GetDimensionsState (

                     TQ3ViewHintsObject viewHints, 

                     TQ3Boolean *isValid);

viewHints: A view hints object.
isValid: On exit, the current dimension state of the specified view hints object.

DESCRIPTION

The Q3ViewHints_GetDimensionsState function returns, in the isValid parameter, a Boolean value that indicates whether the dimensions in the view hints object specified by the viewHints parameter are to be used (kQ3True ) or not (kQ3False ).

Q3ViewHints_SetDimensionsState

You can use the Q3ViewHints_SetDimensionsState function to set the dimension state associated with a view hints object.



 
TQ3Status Q3ViewHints_SetDimensionsState (

                     TQ3ViewHintsObject viewHints, 

                     TQ3Boolean isValid);

viewHints: A view hints object.
isValid: A dimension state.

DESCRIPTION

The Q3ViewHints_SetDimensionsState function sets the dimension state of the view hints object specified by the viewHints parameter to the value passed in the isValid parameter.

Q3ViewHints_GetDimensions

You can use the Q3ViewHints_GetDimensions function to get the dimensions associated with a view hints object.



 
TQ3Status Q3ViewHints_GetDimensions (

                     TQ3ViewHintsObject viewHints, 

                     unsigned long *width, 

                     unsigned long *height);

viewHints: A view hints object.
width: On exit, the width of the specified view hints object.
height: On exit, the height of the specified view hints object.

DESCRIPTION

The Q3ViewHints_GetDimensions function returns, in the width and height parameters, the current width and height associated with the view hints object specified by the viewHints parameter.

Q3ViewHints_SetDimensions

You can use the Q3ViewHints_SetDimensions function to set the dimensions associated with a view hints object.



 
TQ3Status Q3ViewHints_SetDimensions (

                     TQ3ViewHintsObject viewHints, 

                     unsigned long width, 

                     unsigned long height);

viewHints: A view hints object.
width: The desired width of the view hints object.
height: The desired height of the view hints object.

DESCRIPTION

The Q3ViewHints_SetDimensions function sets the width and height of the view hints object specified by the viewHints parameter to the values passed in the width and height parameters.

Q3ViewHints_GetMaskState

You can use the Q3ViewHints_GetMaskState function to get the mask state associated with a view hints object.



 
TQ3Status Q3ViewHints_GetMaskState (

                     TQ3ViewHintsObject viewHints, 

                     TQ3Boolean *isValid);

viewHints: A view hints object.
isValid: On exit, the current mask state of the specified view hints object.

DESCRIPTION

The Q3ViewHints_GetMaskState function returns, in the isValid parameter, a Boolean value that determines whether the mask associated with the view hints object specified by the viewHints parameter is to be used (kQ3True ) or not (kQ3False ).

Q3ViewHints_SetMaskState

You can use the Q3ViewHints_SetMaskState function to set the mask state associated with a view hints object.



 
TQ3Status Q3ViewHints_SetMaskState (

                     TQ3ViewHintsObject viewHints, 

                     TQ3Boolean isValid);

viewHints: A view hints object.
isValid: The desired mask state of the specified view hints object.

DESCRIPTION

The Q3ViewHints_SetMaskState function sets the mask state of the view hints object specified by the viewHints parameter to the value specified in the isValid parameter. Set isValid to kQ3True if you want the mask enabled and to kQ3False otherwise.

Q3ViewHints_GetMask

You can use the Q3ViewHints_GetMask function to get the mask associated with a view hints object.



 
TQ3Status Q3ViewHints_GetMask (

                     TQ3ViewHintsObject viewHints, 

                     TQ3Bitmap *mask);

viewHints: A view hints object.
mask: On exit, the mask of the specified view hints object.

DESCRIPTION

The Q3ViewHints_GetMask function returns, in the mask parameter, the current mask for the view hints object specified by the viewHints parameter. The mask is a bitmap whose bits determine whether or not corresponding pixels in the drawing destination are drawn or are masked out. Q3ViewHints_GetMask allocates memory internally for the returned bitmap; when you're done using the bitmap, you should call the Q3Bitmap_Empty function to dispose of that memory.

Q3ViewHints_SetMask

You can use the Q3ViewHints_SetMask function to set the mask associated with a view hints object.



 
TQ3Status Q3ViewHints_SetMask (

                     TQ3ViewHintsObject viewHints, 

                     const TQ3Bitmap *mask);

viewHints: A view hints object.
mask: The desired mask of the specified view hints object.

DESCRIPTION

The Q3ViewHints_SetMask function sets the mask of the view hints object specified by the viewHints parameter to the bitmap specified in the mask parameter. Q3ViewHints_SetMask copies the bitmap to internal QuickDraw 3D memory, so you can dispose of the specified bitmap after calling Q3ViewHints_SetMask .

Q3ViewHints_GetClearImageMethod

You can use the Q3ViewHints_GetClearImageMethod function to get the image clearing method associated with a view hints object.



 
TQ3Status Q3ViewHints_GetClearImageMethod (

                     TQ3ViewHintsObject viewHints, 

                     TQ3DrawContextClearImageMethod *clearMethod);

viewHints: A view hints object.
clearMethod: On exit, the current image clearing method of the specified view hints object. See "Draw Context Data Structure" for the values that can be returned in this parameter.

DESCRIPTION

The Q3ViewHints_GetClearImageMethod function returns, in the clearMethod parameter, a constant that indicates the current image clearing method for the view hints object specified by the viewHints parameter.

Q3ViewHints_SetClearImageMethod

You can use the Q3ViewHints_SetClearImageMethod function to set the image clearing method associated with a view hints object.



 
TQ3Status Q3ViewHints_SetClearImageMethod (

                     TQ3ViewHintsObject viewHints, 

                     TQ3DrawContextClearImageMethod clearMethod);

viewHints: A view hints object.
clearMethod: The desired image clearing method of the specified view hints object. See "Draw Context Data Structure" for the values that can be passed in this parameter.

DESCRIPTION

The Q3ViewHints_SetClearImageMethod function sets the image clearing method of the view hints object specified by the viewHints parameter to the value specified in the clearMethod parameter.

Q3ViewHints_GetClearImageColor

You can use the Q3ViewHints_GetClearImageColor function to get the image clearing color associated with a view hints object.



 
TQ3Status Q3ViewHints_GetClearImageColor (

                     TQ3ViewHintsObject viewHints, 

                     TQ3ColorARGB *color);

viewHints: A view hints object.
color: On exit, the current image clearing color of the specified view hints object.

DESCRIPTION

The Q3ViewHints_GetClearImageColor function returns, in the color parameter, a constant that indicates the current image clearing color for the view hints object specified by the viewHints parameter.

Q3ViewHints_SetClearImageColor

You can use the Q3ViewHints_SetClearImageColor function to set the image clearing color associated with a view hints object.



 
TQ3Status Q3ViewHints_SetClearImageColor (

                     TQ3ViewHintsObject viewHints, 

                     const TQ3ColorARGB *color);

viewHints: A view hints object.
color: The desired image clearing color of the specified view hints object.

DESCRIPTION

The Q3ViewHints_SetClearImageColor function sets the image clearing color of the view hints object specified by the viewHints parameter to the value specified in the color parameter.